<!--
This software was developed at The MITRE Corporation 
in 2004/2006 and has been approved for Public Release; Distribution Unlimited.


		    GNU GENERAL PUBLIC LICENSE
		       Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
                       51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

			    Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software-to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

		    GNU GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term "modification".)  Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

  2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

    a) You must cause the modified files to carry prominent notices
    stating that you changed the files and the date of any change.

    b) You must cause any work that you distribute or publish, that in
    whole or in part contains or is derived from the Program or any
    part thereof, to be licensed as a whole at no charge to all third
    parties under the terms of this License.

    c) If the modified program normally reads commands interactively
    when run, you must cause it, when started running for such
    interactive use in the most ordinary way, to print or display an
    announcement including an appropriate copyright notice and a
    notice that there is no warranty (or else, saying that you provide
    a warranty) and that users may redistribute the program under
    these conditions, and telling the user how to view a copy of this
    License.  (Exception: if the Program itself is interactive but
    does not normally print such an announcement, your work based on
    the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

    a) Accompany it with the complete corresponding machine-readable
    source code, which must be distributed under the terms of Sections
    1 and 2 above on a medium customarily used for software
    interchange; or,

    b) Accompany it with a written offer, valid for at least three
    years, to give any third party, for a charge no more than your
    cost of physically performing source distribution, a complete
    machine-readable copy of the corresponding source code, to be
    distributed under the terms of Sections 1 and 2 above on a medium
    customarily used for software interchange; or,

    c) Accompany it with the information you received as to the offer
    to distribute corresponding source code.  (This alternative is
    allowed only for noncommercial distribution and only if you
    received the program in object code or executable form with such
    an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

  5. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

  7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

  9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation.  If the Program does not specify a
version number of this License, you may choose any version ever
published by the Free Software Foundation.

  10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

			    NO WARRANTY

  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.

		     END OF TERMS AND CONDITIONS

	    How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

    <one line to give the program's name and a brief idea of what it does.>
    Copyright (C) <year>  <name of author>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA


Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) year name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License.  Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items-whatever suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary.  Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
  `Gnomovision' (which makes passes at compilers) written by James Hacker.

  <signature of Ty Coon>, 1 April 1989
  Ty Coon, President of Vice

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.
-->
<body>
<b>Please read this first</b> - Foundation classes and documentation to build
discrete-event simulations.

<p>
<table border="0" width="100%">
<tr>
<td width="60">
   <img src="doc-files/javalogo52x88.gif" alt="Java Logo" border=0 width=52 height=88>
</td>
<td>
  <center>
  <font color="#7e87ce" size="+4"><i>Tortuga</i></font><br>
  <font size="-1"><i>A Discrete Event Simulation Framework</i></font><br>
  <h3>Java Meets Simulation Project<br>
      MITRE Sponsored Research to Improve Java Simulation Performance<br>
      Tortuga Version 4.0.1<br>
      17 December 2007

	  </h3>
  </center>
</td>
<td align=right width="100">
  Project Sites:<br>
  <a href="http://tortuga.mitre.org">User</a><br>
  <a href="http://tortuga-dev.mitre.org">Developer</a>
  <p>
  Contact:<br>
  <a href="mailto:tortuga-list@lists.mitre.org">Tortuga List</a>
  <p>
  <img src="doc-files/mitre_logo.gif" alt="The MITRE Corporation">
</td>
</tr>
</table>


<h3>Contents</h3>
<blockquote>
<b>Building Simulations</b>
<ul>
  <li><a href="#Introduction"><b>Introduction</b></a>
  <li><a href="#SimulationOrganizations"><b>Organizing a Simulation</b></a>
  <ul>
  	<li><a href="#InteractingProcesses"><b>Interacting Processes View</b></a>
  	<ul>
      <li><a href="#ConstructProc"><b>Constructing an Interacting Processes Simulation</b></a>
      <li><a href="#TimeAdvance"><b>Advancing Time</b></a>
      <li><a href="#ActionMethods"><b>Action Methods</b></a>
    </ul>
    <li><a href="#SchedEventsView"><b>Scheduled Events View</b></a>
    <ul>
      <li><a href="#ConstructSched"><b>Constructing a Scheduled Events Simulation</b></a>
      <li><a href="#SchedEvents"><b>Scheduling Events</b></a>
    </ul>
    <li><a href="#MixedViews"><b>Mixing Interacting-Process and Scheduled-Event Views</b></a>
    <li><a href="#Inheritance"><b>Entities and Java Inheritance</b></a>
  </ul>
  <li><a href="#Control"><b>Simulation Control</b></a>
  <ul>
    <li><a href="#Concurrency"><b>Apparent and Actual Concurrency</b></a>
    <li><a href="#Threads"><b>Threads</b></a>
    <li><a href="#InternalControls"><b>Internal Controls</b></a>
    <ul>
      <li><a href="#InitSimulation"><b>Initializing a Simulation</b></a>
      <li><a href="#EndingSimulation"><b>Ending a Simulation</b></a>
      <li><a href="#Notification"><b>Completion Notification</b></a>
      <li><a href="#Pacing"><b>Pacing a Simulation</b></a>
    </ul>
    <li><a href="#ExternalControls"><b>External Controls</b></a>
    <ul>
      <li><a href="#PauseResume"><b>Pause and Resume</b></a>
      <li><a href="#EventListeners"><b>Event Listeners</b></a>
    </ul>
    <li><a href="#Exceptions"><b>Handling Exceptions</b></a>
  </ul>
  <li><a href="#CompilingExecutingSimulations"><b>Compiling and Executing Simulations</b></a>
  <ul>
    <li><a href="#GetStarted"><b>What You Need to Get Started</b></a>
    <li><a href="#DevelopingYourSimulation"><b>Developing Your Simulation With Tortuga</b></a>
    <li><a href="#ExecutingYourSimulation"><b>Executing Your Simulation</b></a>
  </ul>
  <li><b><a href="gui/package-summary.html">Graphical User Interface</a></b>
</ul>

<b>Infrastructure Documentation</b>
<ul>
  <li><a href="#Property"><b>Property File Parameters</b></a>
  <li><a href="#SystemOrganization"><b>System Organization</b></a>
  <li><a href="#TimeSummary"><b>Time Method Summary</b></a>
  <li><a href="#EntityStates"><b>Lifecycle of an Entity</b></a>
</ul>
</blockquote>

<p><p><hr size="10" color="gray"/>
<a name="Introduction"/>
<h2>Introduction</h2>
Tortuga is a package
for building discrete-event simulations.
It is a product of the <i>Java Meets Simulation</i> MITRE-Sponsored Research project.
This package contains the foundation classes needed to build
discrete-event simulations, structured either as interacting processes, or
scheduled events, or a mixture.
<p>
All simulations evolve simulated time to model some aspect of the real world.
This package assumes that a simulation consists of a set of entities and their environment
that evolve time synchronously,
that the entities can interact with each other, and interact with their environment.
Each entity executes activities or events that occur at points in simulated time;
time evolves for that entity during the gaps between the events.
Thus this package supports discrete-event, rather than continuous-time, simulations.
<p>
In the terminology used in this package, an <b>entity</b> is a persistent simulated being.
A <b>simulation</b> is a collection of entities that can interact with each other,
and which share a common definition of simulation time.
Entities are <b>initialized</b> and <b>registered</b> with a <b>simulation</b>.
A simulation is <b>run</b> to execute it and its entities.
<p>
A developer builds a simulation by defining classes of entities, one Java class for each entity type.
All simulation entities extend {@link org.mitre.sim.DefaultEntity DefaultEntity},
or implement the interface {@link org.mitre.sim.ProcessDelegate ProcessDelegate}.
The developer also defines a subclass of {@link org.mitre.sim.Simulation Simulation}.
An instance of a {@link org.mitre.sim.Simulation Simulation} subclass represents a
group of entities in a single simulation.
<p>
This package constitutes the application programmer's interface to a larger Java framework.
The framework comprises this package, an implementation of a simulation executive
that animates simulations built with the framework, and a Graphical User Interface (GUI) package,
{@link org.mitre.sim.gui}, that provides control over and visibility into an executing simulation.
Packages marked as "Supporting infrastructure" facilitate simulation functioning but
their structure and documentation are not intended for a general audience.

<p><p><hr size="10" color="gray">
<a name="SimulationOrganizations"/>
<h2>Organizing A Simulation</h2>
Discrete-event simulations can be organized in different ways.
Two popular organizing principles, or views, of discrete-event simulations are the
interacting-process view and the scheduled-events view.
This simulation framework supports both views, and each is described below.
An entity can exploit either or both views.
A simulation can include entities that support either view.

<p><p><hr size ="5" color="gray"/>
<a name="InteractingProcesses"/>
<h3>Interacting Processes View</h3>
<blockquote>
The simulation structure that has the greatest intuitive appeal is the process-interaction method.
The notion is that the computer program should emulate the flow of an object through the system.
The entity moves as far as possible in the system until it is delayed, enters an activity,
or exits from the system.
When the entity's movement is halted, the clock advances to the time of the next movement of any entity.
This flow, or movement, describes in sequence all the states that the object can attain in the system.
[J. Banks, <i>Handbook of Simulation</i>, Wiley, 1998]
</blockquote>
This section describes the framework's support for entities viewed as interacting processes.

<a name="ConstructProc"/>
<h4>Constructing an Interacting Processes Simulation</h4>
A developer builds a simulation by defining classes of entities, one Java class for each entity type.
Java class {@link org.mitre.sim.DefaultEntity DefaultEntity}
is the base class for simulation entities.
The developer also defines a subclass of {@link org.mitre.sim.Simulation Simulation}.
An instance of a {@link org.mitre.sim.Simulation Simulation} subclass represents a
group of entities in a single simulation.
<table cols=1 border=1>
  <tr bgcolor="#99cccc"><td>
<h3>Example: Constructing an Interacting Processes Simulation</h3>
This example constructs a simple simulation that
adheres to the interacting-processes view of discrete-event simulation.
Two instances of class <code>MyEntity</code> run in the same simulation;
each instance has a different name but the same behavior.
The class diagram for this simulation is:
<center><img src="doc-files/FirstExample.png" alt="First Example Class Diagram"></center>
</td></tr>
<tr bgcolor="#99cccc"><td>
The class MySimulation contains the <code>main</code> method that  runs the simulation by
creating a new instance of itself and invoking the framework method
{@link org.mitre.sim.Simulation#run() run} on that instance.
The framework also defines an
{@link org.mitre.sim.Simulation#initialize() initialize}
method that may be overridden by classes extending
{@link org.mitre.sim.Simulation Simulation}.
The executive executes the {@link org.mitre.sim.Simulation#initialize() initialize} method when simulation
time is zero and before simulation time begins to advance.
MySimulation creates two instances of MyEntity and affiliates them with the simulation using the
{@link org.mitre.sim.Simulation#register(EntityDelegate) register} framework method.
Entities not registered with a simulation are ignored by the executive.
This source code is available in
<a href="doc-files/examples.tar">tar</a> and
<a href="doc-files/examples.zip">zip</a> archive formats.
<blockquote>
<pre>
<b>class</b> MyEntity <b>extends</b> DefaultEntity {

  <b>public void</b> agenda() {
  }
}

<b>public class</b> MySimulation <b>extends</b> Simulation {

  <b>public void</b> initialize() {
    register(<b>new</b> MyEntity("Foo"));
    register(<b>new</b> MyEntity("Bar"));
  }
  <b>public static void</b> main(String[] args) {
    <b>new</b> MySimulation().run();
  }
}
</pre>
</blockquote>
</td></tr></table>
<p>

<a name="TimeAdvance"/>
<h3>Advancing Time</h3>
Simulations manipulate simulation time, normally relying on an executive to
orchestrate the execution of a set of entities.
The executive uses simulation time to decide the sequence of entity execution.
Entities assign values of simulation time to their individual activities.
The executive uses this assignment to start, suspend, resume, and terminate entity execution.
This manipulation of entity execution allows the executive to create causal relationships in the simulation.
So, if an entity assigns event <b>A</b> to simulation time <i>t</i> and another entity
assigns event <b>B</b> to time <i>t</i>+1,
then event <b>A</b> occurs before event <b>B</b>.
<p>
Entities assign simulation time to their computations using inherited framework methods
defined on class {@link org.mitre.sim.DefaultEntity DefaultEntity}. This section introduces the
{@link org.mitre.sim.DefaultEntity#waitForTime(double) waitForTime(x)} method that always
returns control to the entity
after <code>x</code> units of time have elapsed.
Other methods, described later, provide more complex control of simulated time.
<p>
<table cols=1 border=1>
  <tr bgcolor="#99cccc"><td>
<h3>Example: Advancing Time</h3>
This example extends the simulation constructed in the previous section.
Here, class MyEntity displays the string "Hello", "Still here",
and "Good Bye" at three different points in the evolution of simulation time.
As before, two instances of class <code>MyEntity</code> run in the same simulation.
Each instance has a different name but the same behavior.
This example illustrates:
<ul>
  <li>Implicit assignment of entity computations to specific values of simulation time and
  <li>Simulation executive action to coordinate the execution of multiple entities.
</ul>
</td></tr>
<tr bgcolor="#99cccc"><td>
The first action in the MyEntity {@link org.mitre.sim.Entity#agenda() agenda}
displays the string "Hello" using convenience method
{@link org.mitre.sim.Entity#info(String) info}.
This action is implicitly assigned a simulation time value of zero.
The next statement in the agenda is <code>waitForTime(2.0)</code>.
The {@link org.mitre.sim.Entity#waitForTime(double) waitForTime} invocation tells the executive that the entity
wants to place 2.0 units of simulation time between the display of string "Hello" and
the display of "Still here."
This implicitly assigns a simulation time value of 2.0 to the display of string "Still here."
The fourth statement, <code>waitForTime(3.0)</code>, places 3.0 units of simulation time between the
display of "Still here" and the display of "Good Bye."
The display of "Good Bye" is thus assigned a simulation time of 5.0.
<p>
The class MySimulation contains the <code>main</code> method that runs the simulation
by creating a new instance of itself and invoking the framework method
{@link org.mitre.sim.Simulation#run() run} on that instance.
It also contains method
{@link org.mitre.sim.Simulation#initialize() initialize};
the executive executes this method when simulation
time is zero and before simulation time begins to advance.
MySimulation creates two instances of MyEntity and affiliates them with the simulation using the
{@link org.mitre.sim.Simulation#register(EntityDelegate) register} framework method.
This source code is available in
<a href="doc-files/examples.tar">tar</a> and
<a href="doc-files/examples.zip">zip</a> archive formats.
<blockquote>
<pre>
public final class MyEntity extends DefaultEntity {

    public void agenda() {
    	info("Hello");
    	waitForTime(2.0);
    	info("Still here");
    	waitForTime(3.0);
    	info("Good Bye");
    }
}

public final class MySimulation extends Simulation {

  public void initialize() {
    register(new MyEntity(), "Foo");
    register(new MyEntity(), "Bar");
  }

  public static void main(String[] args) {
    new MySimulation().run();
  }
}
</pre>
</blockquote>
</td></tr>
<tr bgcolor="#99cccc"><td>
In the output of MySimulation (below),
the first line contains infrastructure version information displayed by the executive.
In the rest of the output, {@link org.mitre.sim.Entity#info(String) info}
adds current simulation time and the entity name to the supplied message string.
<p>
The output demonstrates the action of the executive both to assign simulation time to entity
computations and to coordinate the execution of multiple entities.
The 2.0 and 3.0 unit waits between the messages caused "Hello" to receive
a simulation time of 0.0, "Still here" a value of 2.0, and "Good Bye" a value of 5.0 (2.0 + 3.0).
The action of the two instances of MyEntity, Foo and Bar, was interleaved by the executive
to maintain proper temporal ordering. Observe that both entities displayed "Hello" before either entity displayed
"Still here."
<blockquote>
<pre>
Tortuga, Pausing Exec 0.3 TreeMap 1.1, Tiger Flow 0.9.3, Java HotSpot(TM) Client VM 1.6.0_03-b05
0.000 Foo Hello
0.000 Bar Hello
2.000 Foo Still here
2.000 Bar Still here
5.000 Foo Good Bye
5.000 Bar Good Bye
</pre>
</blockquote>
</td></tr></table>

<a name="ActionMethods"/>
<h3>Action Methods</h3>
Simulation entities must be able to affect each other in simulation time.
The previous section showed an entity's proactive, <i>i.e.</i>, self-initiated,
behavior.
This section presents a reactive behavior mechanism that lets
entities interact directly.
This mechanism supports
<ul>
  <li>Creation of services offered by one entity and employed by others,
  <li>Control of entity behavior while offering services, and
  <li>Management of the time span over which services are offered.
</ul>
Entities offer services to each other by creating action methods.
An <b>action method</b> is a method added to a subclass of
{@link org.mitre.sim.DefaultEntity DefaultEntity} that contains an invocation of
{@link org.mitre.sim.Entity#actionOccurred(Enum) actionOccurred}.
Action methods are different from other methods in that their invocation can change the
control flow of the entity that offers them.
Specifically, receipt of an action method invocation can affect when
{@link org.mitre.sim.Entity#waitForAction(double, Enum) waitForAction} invocations return.
<p>
This section also introduces the framework method
{@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction}.
With this call, the entity waits for an certain amount of time to pass.
The difference between
{@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction(t, enumToken)}
and
{@link org.mitre.sim.Entity#waitForTime(double) waitForTime(t)}
is how they handle action methods.
When {@link org.mitre.sim.Entity#waitForTime(double) waitForTime(t)} is invoked,
the framework method always returns control after exactly <i>t</i> units of simulation time have passed.
During those <i>t</i> units of simulation time, the entity could have received any number of
action methods invocations.
When {@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction(t, enumToken)} is used, control returns
when either <i>t</i> units of simulation time have passed or an
action method invocation has been received.
<p>
Method {@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction} returns an
<code>enum</code> constant that conveys the reason the call returned.
The call can return either because <i>t</i> units of simulation time have passed or one of perhaps
several different action methods was invoked.
An <code>enum</code> constant is supplied when
{@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction(t, enumToken)}
is invoked.
If the call returns because simulation time has passed, that <code>enum</code> constant
is returned.
By definition, each action method contains a call to
{@link org.mitre.sim.Entity#actionOccurred(Enum) actionOccurred(enumToken)}.
Each such call should supply a different <code>enum</code> token.
If the
{@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction(t, enumToken)}
call returns because of invocation of a specific action method, the <code>enum</code>
supplied with that action method's <code>actionOccurred</code> invocation is returned.
<p>
As illustrated below, the user defines an <code>enum</code> class with constants for a
time return, and for each action method defined on the entity.
The <code>enum</code> returned from
{@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction(t, enumToken)}
typically is cast to the user's <code>enum</code> type and used in a <code>switch</code>
statement.

<table cols=1 border=1>
  <tr bgcolor="#99cccc"><td>
<h3>Example: Action Methods</h3>
This example simulation has two directly interacting entities.
One entity employs a service provided by a second entity.
The second entity is mostly reactive but imposes constraints over the timing of the service being offered.
The class diagram for the example program is
<center><img src="doc-files/ActionMethods.png" alt="Action Method Class Diagram"></center>
</td></tr>
<tr bgcolor="#99cccc"><td>
<code>PhilanthropistModel</code> is a proactive entity that accepts an instance of
<code>GoodCauseModel</code> when it is constructed.
At two different points in simulation time, <code>PhilanthropistModel</code> interacts with
the <code>GoodCauseModel</code> entity to make a donation using the <code>actionDonate</code>
action method.
This source code is available in
<a href="doc-files/examples.tar">tar</a> and
<a href="doc-files/examples.zip">zip</a> archive formats.
<blockquote>
<pre>
public class PhilanthropistModel extends DefaultEntity {
  GoodCauseModel recipient;

    public PhilanthropistModel(GoodCauseModel gcm) {
      recipient = gcm;
    }

    public void agenda() {
      info("Hello");
      waitForTime(1.0);
      recipient.actionDonate("Food");
      waitForTime(1.0);
      recipient.actionDonate("Shelter");
      waitForTime(1.0);
      info("Good Bye");
    }
}
</pre>
</blockquote>
</td></tr>
<tr bgcolor="#99cccc"><td>
<code>GoodCauseModel</code> accepts donations; however,
if four units of simulation time elapse without a donation, the <code>GoodCauseModel</code>
displays the message "No donations received in last 4 hours, going home." and then stops.
<code>GoodCauseModel</code> uses the
<code>enum</code> constant returned by
{@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction}
to control its main loop.
These constants are defined in <code>GoodCauseReturn</code> as shown below.
If {@link org.mitre.sim.Entity#waitForAction(double,Enum) wiatForAction}
returns anything other than <code>GoodCauseReturn.TIME</code>,
then a donation was received in less than four units of time and <code>GoodCauseModel</code>
waits for more donations by remaining in the loop and calling
{@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction} again.
If the return value is <code>GoodCauseReturn.TIME</code>,
four units of time have passed without a donation and
<code>GoodCauseModel</code> gives up by exiting its main loop, displaying a message, and
ending its {@link org.mitre.sim.Entity#agenda() agenda}.
<blockquote>
<pre>
public class GoodCauseModel extends DefaultEntity {

    public void actionDonate(String donation) {
      info(donation + " received");
      GoodCauseReturn token;
      if (donation.equals("Food")) token = GoodCauseReturn.FOOD;
      else if (donation.equals("Shelter")) token = GoodCauseReturn.SHELTER;
      else token = GoodCauseReturn.OTHER;
      actionOccurred(token);
    }

    public void agenda() {
      while ((GoodCauseReturn)waitForAction(4.0, GoodCauseReturn.TIME) != GoodCauseReturn.TIME) {}
      info("No donations received in last 4 hours, going home.");
    }
}

public enum GoodCauseReturn {
	TIME,
	FOOD,
	SHELTER,
	OTHER,
}

</pre>
</blockquote>
</td></tr>
<tr bgcolor="#99cccc"><td>
The <code>CharitySim</code> class sets the context for the simulation.
It creates a single instance of <code>GoodCauseModel</code> and assigns it to the variable
<code>recipient</code>.
This is done so that the new instance can be passed to the framework method
{@link org.mitre.sim.Simulation#register(org.mitre.sim.EntityDelegate) register}
and provided to the <code>PhilanthropistModel</code> constructor.
<blockquote>
<pre>
public class CharitySim extends Simulation {

  public void initialize() {
    GoodCauseModel recipient = new GoodCauseModel();
    register(recipient, "GoodCause");
    register(new PhilanthropistModel(recipient), "Philanthropist");
  }

  public static void main(String[] args) {
    new CharitySim().run();
  }
}
</pre>
</blockquote>
</td></tr>
<tr bgcolor="#99cccc"><td>
The simulation output shows the interaction between the
<code>Philanthropist</code> and the <code>GoodCause</code>.
<code>Philanthropist</code> begins with the message "Hello,"
waits 1.0 units of time, and then makes a food donation.
The corresponding output shows the <code>Philanthropist</code> message "Hello"
at time 0.0 and a message from <code>GoodCause</code> at time 1.0 acknowledging receipt of the food.
The invocation of the action method <code>actionDonate(String donation)</code> caused the
{@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction} invocation to return
with a value of <code>GoodCauseReturn.FOOD</code> after a wait of only 1.0 units of time.
Since it received a return value other than <code>GoodCauseReturn.TIME</code>,
the main loop in <code>GoodCause</code> makes a second
call to
{@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction}.
<p>
<code>Philanthropist</code> waits another 1.0 units of time and donates shelter.
<code>GoodCause</code> acknowledges the donation of shelter with a message at time 2.0.
Finally, <code>Philanthropist</code> waits 1.0 unit of time, says "Good Bye," and ends.
As this was the third time <code>Philanthropist</code> waited for 1.0 units of time, the
"Good Bye" message is associated with simulation time 3.0.
At simulation time 3.0, 1.0 units of time have elapsed since the last donation.
<code>GoodCause</code> is waiting in a call to
{@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction}
and has 3.0 units of time left until
{@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction}
returns with a value of <code>GoodCauseReturn.TIME</code>.
A return value of <code>GoodCauseReturn.TIME</code> lets <code>GoodCause</code> exit
its main loop and then display its final message.
The time associated with the "No donations received in last 4 hours, going home."
message is 6.0, which is 4.0 units of time after the last donation at simulation
time 2.0.
<blockquote>
<pre>
Tortuga, Pausing Exec 0.3 TreeMap 1.1, Tiger Flow 0.9.3, Java HotSpot(TM) Client VM 1.6.0_03-b05
0.000 Philanthropist Hello
1.000 GoodCause Food received
2.000 GoodCause Shelter received
3.000 Philanthropist Good Bye
6.000 GoodCause No donations received in last 4 hours, going home.
</pre>
</blockquote>
</td></tr></table>


<p><p><hr size="5" color="gray"/>
<a name="SchedEventsView"/>
<h3>Scheduled Events View</h3>
<blockquote>
The basic concept of the event-scheduling method is to advance time to
when something next happens.
This usually releases a resource ...
The event then reallocates available
objects or entities by scheduling activities where they can now participate ...
Time is advanced to the next scheduled event (usually the end of an activity)
and activities are examined to see if any can now start as a consequence.
[J. Banks, <i>Handbook of Simulation</i>, Wiley, 1998]
</blockquote>
This section presents a <b>scheduled-event</b> view of simulation.

<a name="ConstructSched"/>
<h4>Constructing a Scheduled Events Simulation</h4>
A developer builds a simulation by defining classes of entities, one Java class for each entity type.
The Java class {@link org.mitre.sim.DefaultEntity DefaultEntity} can be the base class
for simulation entities.
The developer also defines a subclass of {@link org.mitre.sim.Simulation Simulation}.
An instance of a {@link org.mitre.sim.Simulation Simulation} subclass represents a
group of entities in a single simulation.
<table cols=1 border=1>
  <tr bgcolor="#99cccc"><td>
<h3>Example: Constructing a Scheduled Events Simulation</h3>
This example constructs a simple simulation that
adheres to the event scheduling view of discrete-event simulation.
Two instances of class <code>MyEntity</code> run in the same simulation;
each instance has a different name but the same behavior.
The class diagram for this simulation is:
<center><img src="doc-files/FirstExample.png" alt="First Scheduled Example Class Diagram"></center>
</td></tr>
<tr bgcolor="#99cccc"><td>
The class MySimulation contains the <code>main</code> method that  runs the simulation by
creating a new instance of itself and invoking the framework method
{@link org.mitre.sim.Simulation#run() run} on that instance.
The framework also defines an
{@link org.mitre.sim.Simulation#initialize() initialize}
method that may be overridden by classes extending
{@link org.mitre.sim.Simulation Simulation}.
The executive executes the {@link org.mitre.sim.Simulation#initialize() initialize} method when simulation
time is zero and before simulation time begins to advance.
MySimulation creates two instances of MyEntity and affiliates them with the simulation using the
{@link org.mitre.sim.Simulation#register(EntityDelegate) register} framework method.
Entities not registered with a simulation are ignored by the executive.
This source code is available in
<a href="doc-files/examples.tar">tar</a> and
<a href="doc-files/examples.zip">zip</a> archive formats.
<blockquote>
<pre>
class MyEntity extends DefaultEntity {

  public void initialize() {
  }
}

public class MySimulation extends Simulation {

  public void initialize() {
    register(new MyEntity("Foo"));
    register(new MyEntity("Bar"));
  }
  public static void main(String[] args) {
    new MySimulation().run();
  }
}
</pre>
</blockquote>
</td></tr></table>
<p>
<a name="SchedEvents"/>
<h3>Scheduling Events</h3>
The scheduled-event view of simulation sees the world as a collection of
events rather than entities.
An
<a name="DefineEvent"/>
<b>event</b> is a block of code executed at one or more points in simulation time.
A simulation contains a dynamic collection of scheduled events, where a
scheduled event is the pairing of an event (a block of code) with a value
of simulation time specifying when the code should be executed.
The executive executes scheduled events in order of the time value
associated with each event.
Once executed, the scheduled event is removed from the collection.
<p>
Scheduled events are added to the collection by events themselves.
Events create new scheduled events by invoking a framework service that
associates the name of an event with an amount of simulation time that
must pass before the event is executed.
In this framework, an event is any {@link org.mitre.sim.DefaultEntity  DefaultEntity}
method other
than an <code>agenda</code> method.
Events are scheduled using the
{@link org.mitre.sim.Entity#schedule(java.lang.String,double, Object[]) schedule}
framework service.
This service can be used to schedule events from any entity method, including the
<code>agenda</code>.
<p>
Methods used as events can receive arguments.
Arguments to a scheduled event are stored by the framework when the event is scheduled
and are then passed to the event method at the time it is invoked.
Arguments are passed to the framework as an array of <code>Object</code>s using the
{@link org.mitre.sim.Entity#schedule(java.lang.String, double, Object[]) schedule}
framework service.
When an event is scheduled using this service, the framework determines the class of
each supplied argument.
It uses the name of the method plus the list of argument class names
to find the method for the event.
If a method with the specified signature cannot be found, the exception
<code>java.lang.IllegalArgumentException</code> is thrown.
<p>
A scheduled-event simulation is simply a process in which events execute and create
other scheduled events.
To start this process, a mechanism is needed to identify and execute the initial event.
An initial event, or, more likely, a chain of events, can be scheduled in the entity's
{@link org.mitre.sim.EntityDelegate#initialize() initialize} method.
The framework calls this method once after the entity has been registered.
The code of the initial event can schedule other events, creating a chain of events.
<p>
<table cols=1 border=1>
  <tr bgcolor="#99cccc"><td>
<h3>Example: Scheduling Events</h3>
The <code>SchedEventSim</code> simulation below creates a single instance
of class <code>SchedEntity</code>.
That entity instance, in turn, creates a chain of scheduled events.
The scheduled events are method <code>eventOne</code> at time 2.0 and then method
<code>eventTwo</code> at time 5.0.
The source code for this example is available in
<a href="doc-files/examples.tar">tar</a> and
<a href="doc-files/examples.zip">zip</a> archive formats.
<blockquote>
<pre>
public class SchedEntity extends DefaultEntity {

    public void eventOne(){
      info("Event One");
      schedule("eventTwo", 3.0);
    }

    public void eventTwo(){
      info("Event Two");
    }

    public void initialize() {
      info("Hello");
      schedule("eventOne", 2.0);
      info("Good Bye");
    }
}

public class SchedEventSim extends Simulation {

  public void initialize() {
    register(new SchedEntity(), "SchedEntity");
  }

  public static void main(String[] args) {
    new SchedEventSim().run();
  }
}
</pre>
</blockquote>
<tr bgcolor="#99cccc"><td>
The executive invokes the initialize method of SchedEntity at simulation time zero.
It displays the message "Hello", schedules an event, and
displays the message "Good Bye" all at simulation time zero.
The <code>eventOne</code> method displays the message "Event One"
at time 2.0 because it was scheduled at time zero with a 2.0
time unit delay.
The <code>eventTwo</code> method displays the message "Event Two"
at time 5.0 because it was scheduled by <code>eventOne</code> at
time 2.0 with a requested delay of 3.0.
Note that events continued to execute even though the initialize method
finished execution at time zero.
<blockquote>
<pre>
Tortuga, Pausing Exec 0.3 TreeMap 1.1, Tiger Flow 0.9.3, Java HotSpot(TM) Client VM 1.6.0_03-b05
0.000 SchedEntity Hello
0.000 SchedEntity Good Bye
2.000 SchedEntity Event One
5.000 SchedEntity Event Two
</pre>
</blockquote>
</td></tr></table>

<p><p><hr size ="5" color="gray"/>
<a name="MixedViews" />
<h3>Mixing Interacting-Process and Scheduled-Event Views</h3>
The event scheduling capability works
in harmony with the <a href="#TimeAdvance">time advancement</a> services
used by interacting-process simulations.
Entities can simultaneously control their agendas
with <a href="#TimeAdvance">time advancement</a> services and
schedule chains of events as long as they observe the following:
<ul>
  <li>The agenda can invoke <a href="#TimeAdvance">time advancement</a> services and
  {@link org.mitre.sim.Entity#schedule(java.lang.String, double,Object[]) schedule} events.
  <li>Entity methods used for scheduled events can schedule other events including themselves.
  <li>The agenda method cannot be scheduled as an event.
  <li>Scheduled event methods cannot use <a href="#TimeAdvance">time advancement</a> services.
  <li>Entity instances can only schedule events using their own methods.
</ul>
<table cols=1 border=1>
  <tr bgcolor="#99cccc"><td>
<h3>Example: Mixed Process and Scheduled Events</h3>
The <code>MixedModeSim</code> simulation below creates a single instance
of class <code>MixedModeEntity</code>
and informs the executive that the simulation should be stopped
after 9.0 units of simulation time have passed.
That entity instance, in turn, creates a chain of scheduled events.
The agenda remains active and performs operations
in parallel with the scheduled event execution.
The source code for this example is available in
<a href="doc-files/examples.tar">tar</a> and
<a href="doc-files/examples.zip">zip</a> archive formats.
<blockquote>
<pre>
public class MixedModeSim extends Simulation {

  public void initialize() {
    register(new MixedModeEntity(), "MixedModeEntity");
    setTimeLast(9.0);
  }

  public static void main(String[] args) {
    new MixedModeSim().run();
  }
}

public class MixedModeEntity extends DefaultEntity {

    public void eventOne(){
      info("Event One");
      schedule("eventTwo", 3.0, new Object[] {"Fa "});
    }

    public void eventTwo(String message){
      info("Event Two " + message);
      schedule("eventTwo", 1.5, new Object[] {message + "La "});
    }

    public void agenda() {
      info("Hello");
      waitForTime(1.0);
      schedule("eventOne", 2.0);
      waitForTime(4.0);
      info("Good Bye");
    }
}
</pre>
</blockquote>
<tr bgcolor="#99cccc"><td>
The <code>agenda</code> begins execution at time zero and displays the message "Hello."
It waits 1.0 units of time then schedules method <code>eventOne</code> with a 2.0 time
unit delay.
This means <code>eventOne</code> is executed at time 3.0.
It then waits for 4.0 units of time.
During this delay, time 3.0 arrives and event <code>eventOne</code> displays the message "Event One."
Event <code>eventOne</code> also schedules <code>eventTwo</code> for execution with a
3.0 unit delay.
This gives <code>eventTwo</code> a scheduled execution time of 6.0.
Eventually 4.0 units of time pass for the agenda and it displays the message "Good Bye"
at simulation time 5.0.
When time 6.0 arrives, <code>eventTwo</code> is executed.
It displays message "Event Two Fa" at time 6.0 and reschedules itself to run again in 1.5
units of time.
This is an infinite loop and only ends because <code>MixedModeSim</code> set the
last value of time to 9.0.
<blockquote>
<pre>
Tortuga, Pausing Exec 0.3 TreeMap 1.1, Tiger Flow 0.9.3, Java HotSpot(TM) Client VM 1.6.0_03-b05
0.000 MixedModeEntity Hello
3.000 MixedModeEntity Event One
5.000 MixedModeEntity Good Bye
6.000 MixedModeEntity Event Two Fa
7.500 MixedModeEntity Event Two Fa La
9.000 MixedModeEntity Event Two Fa La La
</pre>
</blockquote>
</td></tr></table>

<p><p><hr size ="5" color="gray"/>
<a name="Inheritance" />
<h3>Entities and Java Inheritance</h3>
In all the examples presented to this point, entity implementation classes
extend {@link org.mitre.sim.DefaultEntity DefaultEntity}.
Because Java allows a class to extend only one class, extending <code>DefaultEntity</code>
means that an entity implementation cannot extend any other class.
This limitation might be unfortunate in the construction of simulations.
There is a way to avoid this limitation, by using a "delegation-style" interface
to the framework.
<p>
In the examples, each entity is represented by an instance of a class that extends
<code>DefaultEntity</code>.
In the delegation scheme, an entity is represented by two objects.
The first is an instance of a user-written class that implements the interface
{@link org.mitre.sim.ProcessDelegate ProcessDelegate}.
The second object is a corresponding instance of the framework class
{@link org.mitre.sim.Entity Entity}.
All the methods defined on {@link org.mitre.sim.DefaultEntity DefaultEntity} are defined on
either <code>ProcessDelegate</code> or <code>Entity</code>.
When user code requires an operation from the framework, it will call a method on
<code>Entity</code>, such as {@link org.mitre.sim.Entity#waitForTime(double) waitForTime}.
When the framework requires an operation on user code, the framework will invoke a method
on <code>ProcessDelegate</code>, such as {@link org.mitre.sim.ProcessDelegate#agenda() agenda}.
<p>
Each entity consists of a <code>ProcessDelegate</code> instance and a corresponding
<code>Entity</code> instance.
The user constructs a <code>ProcessDelegate</code> instance, then
{@link org.mitre.sim.Simulation#register(org.mitre.sim.EntityDelegate) registers} the
<code>ProcessDelegate</code>.
The <code>register</code> invocation returns an instance of
{@link org.mitre.sim.Entity Entity}.
This is the instance that corresponds to the entity.
The framework treats invocations on this instance as invocations on behalf of the entity.
<p>
The user code in the <code>ProcessDelegate</code> must keep a reference to its corresponding
<code>Entity</code> instance if it is to do anything useful.
The <code>ProcessDelegate</code> interface defines a
{@link org.mitre.sim.EntityDelegate#setEntity(org.mitre.sim.Entity) setEntity} method.
During registration, the framework invokes this method with the newly associated <code>Entity</code>.
<p>
Interacting-processes entities will implement
{@link org.mitre.sim.ProcessDelegate ProcessDelegate}.
Scheduled-event entities, that do not require an
{@link org.mitre.sim.ProcessDelegate#agenda() agenda} method, should implement
{@link org.mitre.sim.EntityDelegate EntityDelegate} instead.

<p><p><hr size="10" color="gray"/>
<a name="Control"/>
<h2>Simulation Control</h2>
Simulation control has two domains as seen from the perspective of the simulation executive thread: <b>internal</b> and <b>external</b>.
Internal controls are available to the executive thread and simulation entities.
External controls are available to threads outside the simulation.
Before describing these controls, two preliminary
topics are discussed, concurrency and threads.

<a name="Concurrency"/>
<h3>Apparent and Actual Concurrency</h3>
Fundamental to the interacting-processes view of simulation is the illusion of
concurrency among participating entities.
Each entity can be programmed as if its agenda were running concurrently with other entities' agendas in
simulation time.
In this framework, this does not produce true concurrency in the Java
language sense, with its consequent need to protect shared data structures
from concurrent access.
<i>In one simulation, only one entity actually is computing at a time.</i>
There is only one thread of control within one simulation.
This means that data shared between two entities in the same simulation need
not be protected against concurrent access.
<p>
The qualification "in one simulation" is important.
As discussed in the following section, the framework supports one application
running multiple simulations each in its own thread.
Any data shared between simulations, or between entities in different simulations,
must be protected.
Further, data shared between a simulation in one thread and a GUI running in another
thread must be protected.

<a name="Threads"/>
<h3>Threads</h3>
It is important to understand where the simulation executive get its thread
because the thread source can limit accessibility to external controls.
A simulation executive gets its thread when an instance of
{@link org.mitre.sim.Simulation Simulation}
is created.
This thread can be a new one or the thread that created the
{@link org.mitre.sim.Simulation Simulation} instance.
A new thread is created for the executive by invoking the <code>start</code> method on the
{@link org.mitre.sim.Simulation Simulation} instance.
The thread that created the
{@link org.mitre.sim.Simulation Simulation} instance is
used by the executive when the {@link org.mitre.sim.Simulation#run() run}
method is invoked.
The <code>start</code> method is inherited by
{@link org.mitre.sim.Simulation Simulation} from class
<code>java.lang.Thread</code>.
Method {@link org.mitre.sim.Simulation#run() run}
is specified in interface
<code>java.lang.Runnable</code>.
Reuse of the creating thread is illustrated below:
<blockquote>
<pre>
1  x = 13;
2  <b>new</b> MySimulation().{@link org.mitre.sim.Simulation#run() run()};
3  x = 27;
</pre>
</blockquote>
In line 1, <code>x</code> is set to a value of 13.
In line 2, a new instance of <code>MySimulation</code> is created
and the {@link org.mitre.sim.Simulation#run() run} method
invoked.
The thread of control goes into the
{@link org.mitre.sim.Simulation#run() run} invocation
and does not return until the simulation is finished.
That is, the {@link org.mitre.sim.Simulation#run() run} invocation
<i>blocks</i>.
All aspects of the simulation see the value of <code>x</code> as 13.
In line 3, the simulation is complete and the value of <code>x</code>
is set to 27.
No part of the simulation ever sees <code>x</code> equal to 27.
In this situation it is not possible to use external controls.
<p>
If external controls are needed, the simulation executive must run
in an separate thread.
This is illustrated below:
<blockquote>
<pre>
1  x = 13;
2  <b>new</b> MySimulation().{@link org.mitre.sim.Simulation#start() start()};
3  x = 27;
</pre>
</blockquote>
In line 1, <code>x</code> is set to a value of 13.
In line 2, a new instance of <code>MySimulation</code> is created
and the {@link org.mitre.sim.Simulation#start() start} method invoked.
This creates a new thread for the simulation executive and allows
it to proceed in parallel.
Line 3 sets the value of <code>x</code> to 27.
This may happen before the simulation is finished.
Entities in the simulation may see the value of <code>x</code>
as 13 and then as 27, depending on how the new thread of the simulation is interleaved with
the thread that created it.
In this situation it is possible to use external controls.

<a name="InternalControls" />
<h3>Internal Controls</h3>
The internal simulation controls discussed below are available to a simulation
and its entities.

<a name="InitSimulation"/>
<h4>Initializing a Simulation</h4>
An industrial-strength simulation framework should facilitate the
specification of all initial entities and their relationships.
This is because meaningful simulations usually involve many
initial entities, and the cost of specifying them is a significant
part of the overall cost of the simulation.
Mechanisms that lower the cost of initialization can lower the overall
cost of a simulation.
<p>
The framework provides two methods to assist simulation initialization:
{@link org.mitre.sim.Simulation#initialize() Simulation.initialize} and
{@link org.mitre.sim.EntityDelegate#initialize() initialize}.
The framework calls
{@link org.mitre.sim.Simulation#initialize() Simulation.initialize}
at simulation time zero, before the <code>agenda</code> of any entity begins
or any scheduled events are processed.
The framework supplies a default implementation that does nothing.
A simulation developer can override this implementation;
initial entities should be created and registered here.
The framework calls
{@link org.mitre.sim.Entity#initialize() Entity.initialize}
for each entity before beginning its <code>agenda</code>.
The call might not occur at simulation time zero; an entity
can be registered and begin after time zero.
As with <code>Simulation.initialize</code>, the framework supplies a default empty
implementation that the developer can override.
<code>Entity.initialize</code> is a convenient place for
calculations that must be performed before its <code>agenda</code> begins, and after
entity is registered.

<a name="EndingSimulation"/>
<h4>Ending a Simulation</h4>
A simulation ends for one of the following reasons:
<ul>
  <li>All entities have completed their agendas, and have no scheduled events,
  <li>An entity explicitly stops the simulation, or
  <li>The last value of simulation time arrives.
</ul>
A simulation can be stopped by any entity using the framework method
{@link org.mitre.sim.Entity#stopSimulation() stopSimulation}.
This method informs the executive that the simulation should end
at the current simulation time.
When a simulation is stopped in this way, the notification services described in
section <a href="#Notification">Completion Notification</a> are invoked.
Events scheduled for the current simulation time may not be executed.
<p>
The executive contains a value of simulation time known as the "last value of time."
By default, this value is set to <code>Double.POSITIVE_INFINITY</code>.
Framework method {@link org.mitre.sim.Simulation#setTimeLast(double) setTimeLast}
is available on class {@link org.mitre.sim.Simulation Simulation}
to adjust the last value of simulation time.
The executive stops the simulation when the last value of time arrives.
Events scheduled for the same time as the last value may not be executed.
When a simulation is stopped because it reached the last value of simulation time,
the notification services described in
section <a href="#Notification">Completion Notification</a> are invoked.

<a name="Notification"/>
<h4>Completion Notification</h4>
As described above, an entity or simulation can end in several ways.
Given this uncertainty, framework methods are available that can be overridden.
<ul>
  <li>{@link org.mitre.sim.Entity#entityComplete() entityComplete:}
      Executed as the final step in the life of an entity.
  <li>{@link org.mitre.sim.Simulation#simulationComplete() simulationComplete:}
      Executed when all entities have ended and all their
      {@link org.mitre.sim.Entity#entityComplete() entityComplete} methods are finished.
</ul>
<p>
<table cols=1 border=1>
  <tr bgcolor="#99cccc"><td>
<h3>Example: Entity Initialization and Completion Notification</h3>
This example demonstrates both
{@link org.mitre.sim.Entity Entity}
and {@link org.mitre.sim.Simulation Simulation}
completion handling.
Class <code>InterruptedEntity</code> overrides framework method
{@link org.mitre.sim.Entity#entityComplete() entityComplete}
with a method that displays the message "Entity complete."
The {@link org.mitre.sim.Entity#agenda() agenda}
attempts to display message "Hello" at time 0.0, "Still here" at time 2.0, and "Good Bye" at time 5.0.
This source code is available in
<a href="doc-files/examples.tar">tar</a> and
<a href="doc-files/examples.zip">zip</a> archive formats.
<blockquote>
<pre>
public class InterruptedEntity extends DefaultEntity {

    public void initialize() {
      info("Initialized");
    }

    public void entityComplete() {
      info("Entity complete");
    }

    public void agenda() {
      info("Hello");
      waitForTime(2.0);
      info("Still here");
      waitForTime(3.0);
      info("Good Bye");
    }
}
</pre>
</blockquote>
</td></tr>
<tr bgcolor="#99cccc"><td>
Class <code>FinalSimulation</code> overrides the framework method
{@link org.mitre.sim.Simulation#simulationComplete() simulationComplete}
with a method that displays the message "Simulation complete."
It also uses framework method
{@link org.mitre.sim.Simulation#setTimeLast(double) setTimeLast}
to set the last value of simulation time to 2.5.
<blockquote>
<pre>
public class FinalSimulation extends Simulation {

  public void initialize() {
    register(new InterruptedEntity(), "InterruptedEntity");
    setTimeLast(2.5);
  }

  public void simulationComplete() {
    info("Simulation complete");
  }

  public static void main(String[] args) {
    new FinalSimulation().run();
  }
}
</pre>
</blockquote>
</td></tr>
<tr bgcolor="#99cccc"><td>
The output of the simulation entity <code>InterruptedEntity</code> contains only two of the
three messages in its {@link org.mitre.sim.Entity#agenda() agenda}.
The simulation executive stopped the simulation at time 2.5 and invoked
the completion method for the entity, displaying "Entity complete," and
then the completion method for the simulation, displaying "Simulation complete."
<blockquote>
<pre>
Tortuga, Pausing Exec 0.3 TreeMap 1.1, Tiger Flow 0.9.3, Java HotSpot(TM) Client VM 1.6.0_03-b05
0.000 InterruptedEntity Initialized
0.000 InterruptedEntity Hello
2.000 InterruptedEntity Still here
2.500 InterruptedEntity Entity complete
2.5 FinalSimulation Simulation complete
</pre>
</blockquote>
</td></tr></table>

<a name="Pacing"/>
<h4>Pacing a Simulation</h4>
A simulation can run as fast as its supporting computer permits or it can
be paced by the progress of real time.
By default, the simulation executive executes a simulation as fast as possible.
That is, the simulation completes in the minimum amount of real time.
The {@link org.mitre.sim.Simulation#setPace(long) setPace}
method on class {@link org.mitre.sim.Simulation Simulation}
gives control over the maximum rate at which the simulation evolves time
by specifying the minimum number of real milliseconds that must elapse
for each unit of simulation time.
<p>
It may take more than the specified number of milliseconds to compute one unit of simulation time --
the host computer may not have enough power to achieve the desired rate.
In this case,
{@link org.mitre.sim.Simulation#setPace(long) setPace}
has no effect.
The simulation can be reset to run as fast as possible by invoking the method with a zero argument:
{@link org.mitre.sim.Simulation#setPace(long) setPace(0)}.
<p>
<table cols=1 border=1>
  <tr bgcolor="#99cccc"><td>
<h3>Example: Setting the Simulation Pace</h3>
This example demonstrates the use of framework method
{@link org.mitre.sim.Simulation#setPace(long) setPace}
to control the maximum rate at which the simulation advances simulation time.
Class <code>RocketModel</code> simulates the countdown of a rocket as it prepares for launch.
It displays a message heard at Cape Canaveral: "T minus i seconds"
where i is the number of seconds until launch.
The count goes down from 10 seconds to 1 second.
After that, "Blast off!" is displayed.
The {@link org.mitre.sim.Entity#waitForTime(double) waitForTime} framework method
delays of one unit of simulation time between counts.
This source code is available in
<a href="doc-files/examples.tar">tar</a> and
<a href="doc-files/examples.zip">zip</a> archive formats.
<blockquote>
<pre>
public class RocketModel extends DefaultEntity {

  public void agenda() {
    for (int count = 10; count > 0; count--) {
      info("T minus " + count + " seconds");
      waitForTime(1.0);
    }
    info("Blast off!");
  }
}
</pre>
</blockquote>
</td></tr>
<tr bgcolor="#99cccc"><td>
The <code>LaunchSim</code> class creates one instance of entity <code>RocketModel</code>
and registers it with the simulation executive.
Using {@link org.mitre.sim.Simulation#setPace(long) setPace}
it then directs the infrastructure that at least 1000 milliseconds
(one second) of real time must pass for each unit of simulation time.
<blockquote>
<pre>
public class LaunchSim extends Simulation {

  public void initialize() {
    register(new RocketModel(), "RocketModel");
    setPace(1000);
  }

  public static void main(String[] args) {
    new LaunchSim().run();
  }
}
</pre>
</blockquote>
</td></tr>
<tr bgcolor="#99cccc"><td>
The output of the Launch Simulation shows how the infrastructure creates the desired
pace of simulation.
The output does not appear immediately;
a one second delay occurs between each displayed line.
That is, it took about 10 seconds, as measured by a wrist watch, for
all the output below to appear.
<blockquote>
<pre>
Tortuga, Pausing Exec 0.3 TreeMap 1.1, Tiger Flow 0.9.3, Java HotSpot(TM) Client VM 1.6.0_03-b05
0.000 RocketModel T minus 10 seconds
1.000 RocketModel T minus 9 seconds
2.000 RocketModel T minus 8 seconds
3.000 RocketModel T minus 7 seconds
4.000 RocketModel T minus 6 seconds
5.000 RocketModel T minus 5 seconds
6.000 RocketModel T minus 4 seconds
7.000 RocketModel T minus 3 seconds
8.000 RocketModel T minus 2 seconds
9.000 RocketModel T minus 1 seconds
10.000 RocketModel Blast off!
</pre>
</blockquote>
</td></tr></table>

<a name="ExternalControls"/>
<h3>External Controls</h3>
This section describes the external controls available to threads outside
the simulation and ways for a simulation to communicate with
outside threads.

<a name="PauseResume"/>
<h4>Pause and Resume</h4>
Pause and resume are actions taken by a thread outside the
{@link org.mitre.sim.Simulation Simulation}
instance;
both are methods on instances of
{@link org.mitre.sim.Simulation Simulation}.
They are
<ul>
  <li>{@link org.mitre.sim.Simulation#pauseSimulation() pauseSimulation} -
      Suspend activity in the simulation by pausing the executive.
      Once the executive is paused, simulation time does not advance.
  <li>{@link org.mitre.sim.Simulation#resumeSimulation() resumeSimulation} -
      Resume normal simulation executive operation.
</ul>

<p>
<table cols=1 border=1>
  <tr bgcolor="#99cccc"><td>
<h3>Example: Simulation Pause and Resume</h3>
Like <code>LaunchSim</code> above, <code>DelayedLaunchSim</code> creates and
registers a single instance of <code>RocketModel</code>.
It uses
{@link org.mitre.sim.Simulation#setPace(long) setPace}
to create a rate where one unit of simulation time corresponds to
one second of real time.
The method <code>delay(long)</code> is a convenience to hide the clutter of an exception handler.
<p>
The <code>main</code> method creates a instance of <code>DelayedLaunchSim</code>
and gives it a new thread of control by invoking method {@link org.mitre.sim.Simulation#start() start}.
After line 16 is executed, two threads are running in parallel, one in the
<code>main</code> method and one in the simulation executive.
Line 17 puts the <code>main</code> thread to sleep for 5 seconds.
While the <code>main</code> thread is sleeping, the simulation continues to run.
The <code>main</code> thread wakes up in line 18 and uses the external control
method {@link org.mitre.sim.Simulation#pauseSimulation() pauseSimulation}
to stop the advance of simulation time.
When line 19 is executed, the <code>main</code> thread is put
back to sleep for 5 more seconds.
The simulation executive thread continues in the paused state initiated in line 18.
Finally, after sleeping for 5 seconds, the <code>main</code> thread
wakes up and resumes the executive thread using framework method
{@link org.mitre.sim.Simulation#resumeSimulation() resumeSimulation}.
This source code is available in
<a href="doc-files/examples.tar">tar</a> and
<a href="doc-files/examples.zip">zip</a> archive formats.
<blockquote>
<pre>
 1  <b>public class</b> DelayedLaunchSim <b>extends</b> Simulation {
 2
 3    <b>public void</b> initialize() {
 4      register(<b>new</b> RocketModel(), "RocketModel");
 5      setPace(1000);
 6    }
 7
 8    <b>public void</b> delay(long delay) {
 9      <b>try</b> {
10        Thread.sleep(delay);
11      } <b>catch</b> (Exception e) {}
12    }
13
14    <b>public static void</b> main(String[] args) {
15      DelayedLaunchSim dls = <b>new</b> DelayedLaunchSim();
16      dls.{@link org.mitre.sim.Simulation#start() start()};
17      dls.delay(5000);
18      dls.{@link org.mitre.sim.Simulation#pauseSimulation() pauseSimulation()};
19      dls.delay(5000);
20      dls.{@link org.mitre.sim.Simulation#resumeSimulation() resumeSimulation()};
21    }
22
23  }
</pre>
</blockquote>
</td></tr>
<tr bgcolor="#99cccc"><td>
The output of the Delayed Launch Simulation shows how the infrastructure creates the desired
pace of simulation and the effect of external controls.
While the <code>main</code> thread slept in line 17, the simulation conducted the countdown
from 10 down to 5,
each count taking one second of real time.
After the countdown reached 5, the <code>main</code> thread woke up and paused the
simulation.
This resulted in a 5 second delay after which the countdown resumed at a normal pace.
It takes about 15 seconds, as measured by a wrist watch, for
all the output below to appear.
<blockquote>
<pre>
Tortuga, Pausing Exec 0.3 TreeMap 1.1, Tiger Flow 0.9.3, Java HotSpot(TM) Client VM 1.6.0_03-b05
0.000 RocketModel T minus 10 seconds
1.000 RocketModel T minus 9 seconds
2.000 RocketModel T minus 8 seconds
3.000 RocketModel T minus 7 seconds
4.000 RocketModel T minus 6 seconds
5.000 RocketModel T minus 5 seconds
<i><b>Five second delay</b></i>
6.000 RocketModel T minus 4 seconds
7.000 RocketModel T minus 3 seconds
8.000 RocketModel T minus 2 seconds
9.000 RocketModel T minus 1 seconds
10.000 RocketModel Blast off!
</pre>
</blockquote>
</td></tr></table>
<p>
There is also a way make the simulation run as fast as possible to a
given simulation time, then pause.
See {@link org.mitre.sim.Simulation#pauseAfter(double,SimEventListener) Simulation.pauseAfter}.
</p>
The methods {@link org.mitre.sim.Simulation#pauseSimulation() pauseSimulation},
{@link org.mitre.sim.Simulation#resumeSimulation() resumeSimulation}, and
{@link org.mitre.sim.Simulation#pauseAfter(double,SimEventListener) pauseAfer}
are intended to be called by an external thread, perhaps an application's Swing
event dispatch thread.
Calling these methods from inside an entity will likely deadlock the simulation application.

<p>
<a name="EventListeners"/>
<h4>Event Listeners</h4>
The framework employs an event-listener pattern to support
communications between entities and external processes like
graphical user interfaces.
Developers can create listeners by implementing interface
{@link org.mitre.sim.SimEventListener SimEventListener}.
These listeners wait for the arrival of
{@link org.mitre.sim.SimEvent SimEvent} events.
Currently, {@link org.mitre.sim.PeriodicEntity PeriodicEntity}
is the only source of
{@link org.mitre.sim.SimEvent SimEvents} in the framework.
<p>
{@link org.mitre.sim.PeriodicEntity PeriodicEntity} is a
framework-provided implementation of
{@link org.mitre.sim.EntityDelegate EntityDelegate}.
Instances of
{@link org.mitre.sim.PeriodicEntity PeriodicEntity}
produce a stream of
{@link org.mitre.sim.SimEvent SimEvents} for their
listeners at regular intervals of simulation time.
The amount of simulation time between events is specified
when the instance of
{@link org.mitre.sim.PeriodicEntity PeriodicEntity}
is created.
Listeners are affiliated with an instance of
{@link org.mitre.sim.PeriodicEntity PeriodicEntity}
by the
{@link org.mitre.sim.PeriodicEntity#addSimEventListener(SimEventListener) addSimEventListener}
method and removed with the
{@link org.mitre.sim.PeriodicEntity#removeSimEventListener(SimEventListener) removeSimEventListener}
method.

<p>
<table cols=1 border=1>
  <tr bgcolor="#99cccc"><td>
<h3>Example: Event Listeners</h3>
Class <code>ListenerSim</code> uses
{@link org.mitre.sim.PeriodicEntity PeriodicEntity}
to create periodic events for a listener.
The <code>Listener</code> class extends
{@link org.mitre.sim.SimEventListener SimEventListener} to
become a listener for
{@link org.mitre.sim.SimEvent SimEvent} events.
The listener displays the simulation time of the
{@link org.mitre.sim.SimEvent SimEvent}
events as they are received.
<p>
During initialization, a single instance of
{@link org.mitre.sim.PeriodicEntity PeriodicEntity}
is created and registered with the executive.
The value 1.5, supplied to the
{@link org.mitre.sim.PeriodicEntity PeriodicEntity} constructor,
means that this instance creates events every 1.5 units of
simulation time for all of its registered listeners.
Next, an instance of <code>Listener</code> is created and
added to the list of listeners waiting for
{@link org.mitre.sim.SimEvent SimEvents} to
arrive.
In the last step of initialization,
framework method
{@link org.mitre.sim.Simulation#setTimeLast(double) setTimeLast}
sets the last value of simulation time to 6.0.
Instances of
{@link org.mitre.sim.PeriodicEntity PeriodicEntity}
do not stop on their own so if this step were omitted,
the simulation would not terminate.
This source code is available in
<a href="doc-files/examples.tar">tar</a> and
<a href="doc-files/examples.zip">zip</a> archive formats.
<blockquote>
<pre>
<b>public class</b> ListenerSim <b>extends</b> Simulation {

  <b>public class</b> Listener <b>implements</b> {@link org.mitre.sim.SimEventListener SimEventListener} {
    <b>public void</b> {@link org.mitre.sim.SimEventListener#simEventOccurred simEventOccurred}({@link org.mitre.sim.SimEvent SimEvent} se) {
      info("Event received at " + se.getTime());
    }
  }

  <b>public void</b> initialize() {
    {@link org.mitre.sim.PeriodicEntity PeriodicEntity} generator = new PeriodicEntity(1.5);
    generator.{@link org.mitre.sim.PeriodicEntity#addSimEventListener(SimEventListener) addSimEventListener}(<b>new</b> Listener());
    register(generator);
    setTimeLast(6.0);
  }

  <b>public static void</b> main(String[] args) {
    <b>new</b> ListenerSim().run();
  }

}
</pre>
</blockquote>
</td></tr>
<tr bgcolor="#99cccc"><td>
The output of the Listener Simulation shows that events were produced every 1.5
units of simulation time.
The event stream concluded when the last value of simulation time, 6.0, was reached.
<blockquote>
<pre>
Tortuga, Pausing Exec 0.3 TreeMap 1.1, Tiger Flow 0.9.3, Java HotSpot(TM) Client VM 1.6.0_03-b05
1.5 ListenerSim Event received at 1.5
3.0 ListenerSim Event received at 3.0
4.5 ListenerSim Event received at 4.5
6.0 ListenerSim Event received at 6.0
</pre>
</blockquote>
</td></tr></table>

<a name="Exceptions"/>
<h3>Handling Exceptions</h3>
{@link org.mitre.sim.Entity#agenda() agenda} or
{@link org.mitre.sim.Entity#entityComplete() entityComplete}
methods could throw exceptions.
The simulation executive catches any exception thrown by the
these methods and supplies it to the
{@link org.mitre.sim.Entity#exceptionHandler(Exception e) exceptionHandler}
method below
<blockquote>
<pre>
<b>public void</b> exceptionHandler(Exception e) {
  e.printStackTrace();
}
</pre>
</blockquote>
If this happens, no further attempt is made to run
{@link org.mitre.sim.Entity#agenda() agenda} or
{@link org.mitre.sim.Entity#entityComplete() entityComplete}.
If an exception handler other than the one shown above is needed,
the handler can be overridden.
The executive catches and discards any exceptions thrown by
{@link org.mitre.sim.Entity#exceptionHandler(Exception e) exceptionHandler} itself.

<p><p><hr size ="10" color="gray"/>
<a name="CompilingExecutingSimulations"/>
<h2>Compiling and Executing Simulations</h2>

<a name="GetStarted"/>
<h3>What You Need to Get Started</h3>
<ul>
  <li>Your simulation, as a set of Java classes.
      There are the simple examples in this introduction.
      The example source code is available in
      <a href="http://tortuga.mitre.org/user/3.4/org/mitre/sim/doc-files/examples.tar">tar</a> and
      <a href="http://tortuga.mitre.org/user/3.4/org/mitre/sim/doc-files/examples.zip">zip</a> archive formats.
  <li>A Java development kit.
      The Sun JDK, versions 1.5 or 1.6, will support Tortuga models up to several
      thousand interacting processes, on any platform supported by the JDK.
  <li>The Tortuga software,
      available <a href="http://tortuga.mitre.org/build-4.0/tortuga.jar">here</a>.
</ul>

<a name="DevelopingYourSimulation" />
<h3>Developing Your Simulation with Tortuga</h3>
Tortuga simulations are normal Java programs, requiring nothing special for their development.

<a name="ExecutingYourSimulation"/>
<h3>Executing Your Simulation</h3>
Once you have compiled your simulation, you can execute it like
any Java program.
The Tortuga library (<code>tortuga.jar</code>) must be included on the class path.
Nothing else is required.

<p><p><hr size ="10" color="gray"/>
<a name="Property"/>
<h2>Property File Parameters</h2>
The simulation infrastructure obtains runtime parameters from a Java properties file.
The name of the properties file is <code>sim.properties</code>.
In <code>tortuga.jar</code>, the properties file is located relative to the archive root
at <code>resources/sim.properties</code>.
<p>
In the development repository, the properties file is
resides at <code>sim/resources/sim.properties</code>.
To be accessible at runtime, a copy of the properties file must exist in
<code>sim/classes/resources</code>.
The Ant script <code>sim/build.xml</code> copies
the <code>resources</code> directory as necessary:
Ant target <code>build</code> copies the <code>resources</code> directory to
the <code>sim/classes</code> directory; and
Ant target <code>jar</code> copies the <code>resources</code> directory into the
<code>tortuga.jar</code> archive.
<p>
The property file contents relating to the simulation infrastructure are described below.
Other properties, relating to the GUI, are described in the GUI package documentation.
<br>
<br>
<table align="center" border="1" cols="3" cellspacing="0" cellpadding="3" width="90%">
  <tr bgcolor="#ccccff" align="left" valign="top">
    <th>Property Name</th>
    <th>Description</th>
    <th>Default Value</th>
  </tr>
  <tr>
    <td>org.mitre.sim.EventManager.class</td>
    <td>Event manager class name.</td>
    <td>org.mitre.sim.event. calendar.CalendarImp1</td>
  </tr>
  <tr>
    <td>org.mitre.sim.Executive.class</td>
    <td>Simulation executive class name.</td>
    <td>org.mitre.sim.exec.pausing. PausingExecutive</td>
  </tr>
    <tr>
    <td>org.mitre.sim.Flow.class</td>
    <td>Process lifecycle services class name.</td>
    <td>org.mitre.sim.flow. threads.ThreadFlow</td>
  </tr>
  </tr>
  <tr>
    <td>org.mitre.sim.Simulation.suppressVersionPrint</td>
    <td>If defined, suppresses version print when Simulation constructed.</td>
    <td>undefined</td>
  </tr>
</table>
<br>

<p><p><hr size="10" color="gray"/>
<a name="SystemOrganization"/>
<h2>System Organization</h2>
<center><img src="doc-files/SystemOrganization.jpg" alt="Overall System Class Diagram"></center>

<p><p><hr size="10" color="gray"/>
<a name="TimeSummary"/>
<h2>Time Method Summary</h2>
<table align="center" border="1" cols="5" cellspacing="0" cellpadding="3" width="90%">
  <tr bgcolor="#ccccff" align="left" valign="top">
	<th>Method Invocation at time <code>t<sub>i</sub></code></th>
	<th>Return Description</th>
	<th><i>Action Method</i> Invoked at time <code>t<sub>a</sub></code></th>
	<th>Time Elapses <code>x</code> Units</th>
  </tr>
  <tr>
    <td>{@link org.mitre.sim.Entity#waitForTime(double) waitForTime (x)}</td>
    <td>Return control to the {@link org.mitre.sim.Entity Entity}
        after <code>x</code> units of time have elapsed.
    </td>
    <td>Nothing Happens</td>
    <td>Returns
    </td>
  </tr>
  <tr>
    <td>{@link org.mitre.sim.Entity#waitForAction(double, Enum) waitForAction (x, token)}</td>
    <td>Return control to this {@link org.mitre.sim.Entity Entity}
        when any <i>action method</i> has been
        invoked or <code>x</code> units of time have elapsed.
    </td>
    <td>Returns:<br>
        <code>enum</code> supplied in action method when
        {@link org.mitre.sim.Entity#actionOccurred(Enum) Entity.actionOccurred} was invoked
    </td>
    <td>Returns:<br>
        <code>enum</code> supplied when
        {@link org.mitre.sim.Entity#waitForAction(double, Enum) waitForAction} was invoked
    </td>
  </tr>
</table>

<a name="EntityStates"/>
<h2>Lifecycle of an Entity</h2>
The behavior of an entity can be described as a state machine.
The state transition diagram below shows the lifecycle of an entity from the entity's perspective.
<p>
<center><img src="doc-files/EntityStates.jpg" alt="Entity Life Cycle"></center>
<h3>Entity States</h3>
<ul>
  <li><a name="DefineConstructed"/><b>Constructed:</b>
       The {@link org.mitre.sim.Entity Entity}
       instance has been constructed but not yet registered with a simulation.

  <li><a name="DefineInitializing"/><b>Initializing:</b>
       Sometime after the {@link org.mitre.sim.Entity Entity} is registered
       and before it first enters the Active state, the executive will invoke the
       entity's {@link org.mitre.sim.Entity#initialize() initialize} method.

  <li><a name="DefineActive"/><b>Active:</b>
       This composite state comprises the Computing, Waiting, and Scheduled
       states.

  <li><a name="DefineComputing"/><b>Computing:</b>
       Applies only to a <a href="#DefineProcessEntity">process entity<a/>.
       The simulation executive has passed control to this entity.
       Code in the entity's <code>agenda</code> is executing.
       If <code>agenda</code> code could ask what state it is in, the answer always would
       be "Computing."
       There is only one entity in a simulation in this state at a given time.

  <li><a name="DefineWaiting"/><b>Waiting:</b>
       This composite state comprises the WaitingForTime and WaitingForEntity states.
       A <a href="#DefineProcessEntity">process entity<a/> is waiting for a specific
       value of simulation time to arrive or for an action method invocation.

  <li><a name="DefineWaitingForTime"/><b>WaitingForTime:</b>
       A <a href="#DefineProcessEntity">process entity<a/> is waiting for a specific
       value of simulation time to arrive.

  <li><a name="DefineWaitingForEvent"/><b>WaitingForEvent:</b>
       A <a href="#DefineProcessEntity">process entity<a/> is waiting for a
       or for an action method invocation.

  <li><a name="DefineScheduling"/><b>Scheduling:</b>
       A <a href="#DefineScheduledEntity">scheduled entity<a/> in this state has one
       or more events scheduled.
       A <a href="#DefineProcessEntity">process entity<a/> in this state has returned
       from its <code>agenda</code> method, and has one or more events scheduled.

  <li><a name="DefineCompleting"/><b>Completing:</b>
       The executive has invoked the entity's
       {@link org.mitre.sim.Entity#entityComplete() entityComplete}.

  <li><a name="DefineComplete"/><b>Complete:</b>
       The entity is capable of no further action and awaits garbage collection.
</ul>

<h3>Entity State Transitions</h3>
<ol>
  <li>Instance of an {@link org.mitre.sim.Entity Entity} subclass is
      {@link org.mitre.sim.Simulation#register(EntityDelegate) registered}
      after being constructed.
  <li>The simulation executive selects a <a href="#DefineProcessEntity">process entity<a/>
      for execution for the first time.
      Its {@link org.mitre.sim.Entity#agenda() agenda} is invoked.
  <li>A <a href="#DefineScheduledEntity">scheduled entity<a/>
      schedules its first event.
  <li>The entity {@link org.mitre.sim.Entity#agenda() agenda} invokes the
      {@link org.mitre.sim.Entity#waitForTime(double) waitForTime}
      method.
  <li>The <code>agenda</code> of the waiting entity resumes computation because
      the time desired by the entity arrives.
  <li>The entity {@link org.mitre.sim.Entity#agenda() agenda} invokes the
      {@link org.mitre.sim.Entity#waitForAction(double,Enum) waitForAction}.
  <li>The <code>agenda</code> of the waiting entity resumes computation because either
    <ul>
      <li>An action method is invoked, or
      <li>Simulation time advances enough to accommodate the desired wait.
    </ul>
  <li>The currently computing entity reaches the end of its
      {@link org.mitre.sim.Entity#agenda() agenda} method.
  <li>The entity has no more events scheduled.
  <li>The entity is forced to completion either because
     <ul>
       <li>The simulation is explicitly terminated by invocation of
           {@link org.mitre.sim.Entity#stopSimulation() Entity.stopSimulation}, or
       <li>The last value of simulation time arrived.
     </ul>
  <li>The entity's {@link org.mitre.sim.EntityDelegate#entityComplete() entityComplete} method finishes.
</ol>


<br>
<p><img src="doc-files/mitre_logo.gif"><br>
<font size=-2>Copyright &copy; 2003-2004 The MITRE Corporation</font>
</body>
